/*
 Copyright (C) 2010-2013. 
 Ezequiel Palumbo, Calipsoide FOSS Foundation.
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public License
 along with this program.  If not, see http://www.gnu.org/licenses/. 
 
 Email: contacto@ehpalumbo.com.ar 
*/

package org.calipsoide.dbf2xml.dbf;

import java.util.List;
import java.util.Set;

import org.calipsoide.dbf2xml.model.Field;
import org.calipsoide.dbf2xml.model.Record;

/**
 * 
 * Interface for components that can extract Record from a table with 
 * sequential access. Offers a set of limited query functionalities:
 * <br> 
 * - <i>Projections</i>: records have only a sub set of columns.
 * <br> 
 * - <i>Restrictions</i>: only gets records that have fields with specified values.
 * <br> 
 * - <i>Pagination</i>: allows component to limit the size and position (in table) 
 * of the returned records.
 * <br> 
 * 
 * @since 1.0
 * @author ehpalumbo
 * 
 */
public interface TableDataExtractor {

	/**
	 * 
	 * Enables component to read the table and get only a sub set of columns. 
	 * 
	 * @param projections field names to select
	 * @return this object, for chaining purposes 
	 */
	public abstract TableDataExtractor project(List<String> projections);
	
	/**
	 * 
	 * Enables component to apply restrictions over the records, in order to 
	 * filter them while reading table. 
	 * 
	 * @param restrictions fields to filter records when reading table
	 * @return this object, for chaining purposes 
	 */
	public abstract TableDataExtractor restrict(Set<Field> restrictions);
	
	/**
	 * 
	 * Specifies the number of the record to begin reading. 
	 * Useful to paginate results.
	 * 
	 * @param since record number where to begin 
	 * @return this object, for chaining purposes 
	 */
	public abstract TableDataExtractor from(Integer since);
	
	/**
	 * 
	 * Sets the maximum number of returned records the extractor must get. 
	 * 
	 * @param maximum number limit of results 
	 * @return this object, for chaining purposes 
	 */
	public abstract TableDataExtractor limitTo(Integer maximum);
	
	/**
	 * 
	 * Starts the extraction from table, applying the settings over the 
	 * results.
	 * 
	 * @return the list of matching records
	 */
	public abstract List<Record> extract();

}